Xbasic

sql_upsert Function

Syntax

p result = sql_upsert(A connection,c tablename,c fieldValuePairs [,c primaryKey [, a primaryKeyValue [, L flagExecute [, P e ]]]])

Arguments

connectionCharacter SQL::Connection: Either an open SQL::connection object, or the name of a connection string.
tablenameCharacter: The name of table to update.
fieldValuePairsCharacter: The fields to update with corresponding values specified as either a CR-LF delimited list of the form fieldname=value, or a JSON string (see example). Date values must be specified using yyyy-mm-dd format.
primaryKeyCharacter: The name of primary key field. If primaryKey is multi column use ||| to delimit (e.g. OrderNumber|||PartNumber). If primaryKey is blank or omitted, then the action is automatically assumed to be an INSERT.
primaryKeyValueAny Type: The value of primary key. If primaryKey is multi-column, use ||| to delimit (e.g. 10245|||23). If the primaryKeyValue is blank or omitted, then the action is automatically assumed to be an INSERT.
flagExecuteLogical: Default = .t.. This parameter must always be set to .t.
ePointer: A dot variable with with one or more sub-properties. Used in the case where the fieldValuePairs contains dot variables for the value. For example, assume that one line in the cr-lf delimited list of fieldValuePairs containedname=e.whatname and the e variable that was passed in contained e.whatname = "John Smith", the e.whatname in the fieldValuePairs would be resolved before the SQL was executed.

Returns

resultPointer

Returns an object with the following properties:

errorLogical: Indicates whether or not an error occurred.
errorTextCharacter: If error is true, information about the error.
sqlCharacter: The SQL that was generated.
argumentsCharacter: The XML for the arguments that were generated.
actionCharacter: The action performed. Will be either "Insert" or "Update".
rowsAffectedNumeric: The number of rows affected by the operation if an UPDATE was executed. In some databases (e.g. MySQL) if the record specified by the primary key is not found an error is returned (result.error = .t.), while in other databases (e.g. SQL Server) the result.error flag is .f., but rowsAffected will be 0.
lastInsertedIdentityAny Type: If an INSERT was executed, the value of the primary key field (if its value was auto-generated.)

Description

Updates or Inserts a record in a SQL table.

Discussion

The sql_upsert() function is a high level Xbasic function that complements the sql_update() and sql_insert() functions. The sql_upsert() function will update a record if the record exists in the database. Otherwise it will insert a new record into the database.

Example

dim cn as sql::Connection
cn.open("::Name::myconnstring")
tablename = "mytable"
fieldsValuePairs = <<%str%
name=fred smith
date of birth=1952/12/18
salary=78000
%str%

'You can also specify field values using JSON
fieldsValuePairs = <<%str%
{ 
    "name" : "fred smith",
    "date of birth" : "1954/11/25",
    "salary" : "78000"
}
%str%

primaryKey = "id"
primarykeyValue = "1"

p = sql_upsert(cn,tablename,fieldsValuePairs,primaryKey,primaryKeyvalue)